WAI-ARIA Authoring Practices 1.1

Excerpt

This document provides readers with an understanding of how to use WAI-ARIA 1.1 [WAI-ARIA] to create accessible rich internet applications. It describes considerations that might not be evident to most authors from the WAI-ARIA specification alone and recommends approaches to make widgets, navigation, and behaviors accessible using WAI-ARIA roles, states, and properties. This document is directed primarily to Web application developers, but the guidance is also useful for user agent and assistive technology developers.

1. 1.

   ​1. Introduction​
2. 2.

   ​2. Read Me First​

   1. 1.

      ​2.1 No ARIA is better than Bad ARIA​
   2. 2.

      ​2.2 Browser and Assistive Technology Support​
   3. 3.

      ​2.3 Mobile and Touch Support​
3. 3.

   ​3. Design Patterns and Widgets​

   1. 1.

      ​3.1 Accordion (Sections With Show/Hide Functionality)​
   2. 2.

      ​3.2 Alert​
   3. 3.

      ​3.3 Alert and Message Dialogs​
   4. 4.

      ​3.4 Breadcrumb​
   5. 5.

      ​3.5 Button​
   6. 6.

      ​3.6 Carousel (Slide Show or Image Rotator)​
   7. 7.

      ​3.7 Checkbox​
   8. 8.

      ​3.8 Combo Box​
   9. 9.

      ​3.9 Dialog (Modal)​
   10. 10.

       ​3.10 Disclosure (Show/Hide)​
   11. 11.

       ​3.11 Feed​
   12. 12.

       ​3.12 Grids : Interactive Tabular Data and Layout Containers​
   13. 13.

       ​3.13 Link​
   14. 14.

       ​3.14 Listbox​
   15. 15.

       ​3.15 Menu or Menu bar​
   16. 16.

       ​3.16 Menu Button​
   17. 17.

       ​3.17 Radio Group​
   18. 18.

       ​3.18 Slider​
   19. 19.

       ​3.19 Slider (Multi-Thumb)​
   20. 20.

       ​3.20 Spinbutton​
   21. 21.

       ​3.21 Table​
   22. 22.

       ​3.22 Tabs​
   23. 23.

       ​3.23 Toolbar​
   24. 24.

       ​3.24 Tooltip Widget​
   25. 25.

       ​3.25 Tree View​
   26. 26.

       ​3.26 Treegrid​
   27. 27.

       ​3.27 Window Splitter​
4. 4.

   ​4. Landmark Regions​

   1. 1.

      ​4.1 HTML Sectioning Elements​
   2. 2.

      ​4.2 General Principles of Landmark Design​
   3. 3.

      ​4.3 Landmark Roles​

      1. 1.

         ​4.3.1 Banner​
      2. 2.

         ​4.3.2 Complementary​
      3. 3.

         ​4.3.3 Contentinfo​
      4. 4.

         ​4.3.4 Form​
      5. 5.

         ​4.3.5 Main​
      6. 6.

         ​4.3.6 Navigation​
      7. 7.

         ​4.3.7 Region​
      8. 8.

         ​4.3.8 Search​
5. 5.

   ​5. Providing Accessible Names and Descriptions​

   1. 1.

      ​5.1 What ARE Accessible Names and Descriptions?​
   2. 2.

      ​5.2 How Are Name and Description Strings Derived?​
   3. 3.

      ​5.3 Accessible Names​

      1. 1.

         ​5.3.1 Cardinal Rules of Naming​

         1. 1.

            ​5.3.1.1 Rule 1: Heed Warnings and Test Thoroughly​
         2. 2.

            ​5.3.1.2 Rule 2: Prefer Visible Text​
         3. 3.

            ​5.3.1.3 Rule 3: Prefer Native Techniques​
         4. 4.

            ​5.3.1.4 Rule 4: Avoid Browser Fallback​
         5. 5.

            ​5.3.1.5 Rule 5: Compose Brief, Useful Names​
      2. 2.

         ​5.3.2 Naming Techniques​

         1. 1.

            ​5.3.2.1 Naming with Child Content​
         2. 2.

            ​5.3.2.2 Naming with a String Attribute Via aria-label​
         3. 3.

            ​5.3.2.3 Naming with Referenced Content Via aria-labelledby​
         4. 4.

            ​5.3.2.4 Naming Form Controls with the Label Element​
         5. 5.

            ​5.3.2.5 Naming Fieldsets with the Legend Element​
         6. 6.

            ​5.3.2.6 Naming Tables and Figures with Captions​
         7. 7.

            ​5.3.2.7 Fallback Names Derived from Titles and Placeholders​
      3. 3.

         ​5.3.3 Composing Effective and User-friendly Accessible Names​
      4. 4.

         ​5.3.4 Accessible Name Guidance by Role​
      5. 5.

         ​5.3.5 Accessible name calculation​

         1. 1.

            ​5.3.5.1 Examples of non-recursive accessible name calculation​
         2. 2.

            ​5.3.5.2 Examples of recursive accessible name calculation​
   4. 4.

      ​5.4 Accessible Descriptions​

      1. 1.

         ​5.4.1 Describing Techniques​

         1. 1.

            ​5.4.1.1 Describing by referencing content with aria-describedby​
         2. 2.

            ​5.4.1.2 Describing Tables and Figures with Captions​
         3. 3.

            ​5.4.1.3 Descriptions Derived from Titles​
      2. 2.

         ​5.4.2 Accessible description calculation​
6. 6.

   ​6. Developing a Keyboard Interface​

   1. 1.

      ​6.1 Fundamental Keyboard Navigation Conventions​
   2. 2.

      ​6.2 Discernible and Predictable Keyboard Focus​
   3. 3.

      ​6.3 Focus VS Selection and the Perception of Dual Focus​
   4. 4.

      ​6.4 Deciding When to Make Selection Automatically Follow Focus​
   5. 5.

      ​6.5 Keyboard Navigation Between Components (The Tab Sequence)​
   6. 6.

      ​6.6 Keyboard Navigation Inside Components​

      1. 1.

         ​6.6.1 Managing Focus Within Components Using a Roving tabindex​
      2. 2.

         ​6.6.2 Managing Focus in Composites Using aria-activedescendant​
   7. 7.

      ​6.7 Focusability of disabled controls​
   8. 8.

      ​6.8 Key Assignment Conventions for Common Functions​
   9. 9.

      ​6.9 Keyboard Shortcuts​

      1. 1.

         ​6.9.1 Designing the Scope and Behavior of Keyboard Shortcuts​

         1. 1.

            ​6.9.1.1 Ensure Basic Access Via Navigation​
         2. 2.

            ​6.9.1.2 Choose Appropriate Shortcut Behavior​
         3. 3.

            ​6.9.1.3 Choose Where to Add Shortcuts​
      2. 2.

         ​6.9.2 Assigning Keyboard Shortcuts​

         1. 1.

            ​6.9.2.1 Operating System Key Conflicts​
         2. 2.

            ​6.9.2.2 Assistive Technology Key Conflicts​
         3. 3.

            ​6.9.2.3 Browser Key Conflicts​
         4. 4.

            ​6.9.2.4 Intentional Key Conflicts​
7. 7.

   ​7. Grid and Table Properties​

   1. 1.

      ​7.1 Using aria-rowcount and aria-rowindex​
   2. 2.

      ​7.2 Using aria-colcount and aria-colindex​

      1. 1.

         ​7.2.1 Using aria-colindex When Column Indices Are Contiguous​
      2. 2.

         ​7.2.2 Using aria-colindex When Column Indices Are Not Contiguous​
   3. 3.

      ​7.3 Defining cell spans using aria-colspan and aria-rowspan​
   4. 4.

      ​7.4 Indicating sort order with aria-sort​
8. 8.

   ​8. Intentionally Hiding Semantics with the presentation Role​

   1. 1.

      ​8.1 Effects of Role presentation​
   2. 2.

      ​8.2 Conditions That Cause Role presentation to be Ignored​
   3. 3.

      ​8.3 Example Demonstrating Effects of the presentation Role​
9. 9.

   ​9. Roles That Automatically Hide Semantics by Making Their Descendants Presentational​
10. 10.

    ​A. Indexes​
11. 11.

    ​B. Change History 1. B.1 Changes in July 2019 Publication of Note Release 4 2. B.2 Changes in January 2019 Publication of Note Release 3 3. B.3 Changes in July 2018 Publication of Note Release 2 4. B.4 Changes in December 2017 Publication as Note 5. B.5 Changes in June 2017 Working Draft​
12. 12.

    ​C. Acknowledgements 1. C.1 Major Contributors to Version 1.1 2. C.2 Participants active in the ARIA Authoring Practices Task Force 3. C.3 Other commenters and contributors to Version 1.1 4. C.4 Enabling funders​
13. 13.

    ​D. References 1. D.1 Informative references​

• Enter or Space:

  • When focus is on the accordion header for a collapsed panel, expands the associated panel. If the implementation allows only one panel to be expanded, and if another panel is expanded, collapses that panel.
  • When focus is on the accordion header for an expanded panel, collapses the panel if the implementation supports collapsing. Some implementations require one panel to be expanded at all times and allow only one panel to be expanded; so, they do not support a collapse function.
• Tab: Moves focus to the next focusable element; all focusable elements in the accordion are included in the page Tab sequence.
• Shift + Tab: Moves focus to the previous focusable element; all focusable elements in the accordion are included in the page Tab sequence.
• Down Arrow (Optional): If focus is on an accordion header, moves focus to the next accordion header. If focus is on the last accordion header, either does nothing or moves focus to the first accordion header.
• Up Arrow (Optional): If focus is on an accordion header, moves focus to the previous accordion header. If focus is on the first accordion header, either does nothing or moves focus to the last accordion header.
• Home (Optional): When focus is on an accordion header, moves focus to the first accordion header.
• End (Optional): When focus is on an accordion header, moves focus to the last accordion header.

• The title of each accordion header is contained in an element with role button.
• Each accordion header button is wrapped in an element with role heading that has a value set for aria-level that is appropriate for the information architecture of the page.

  • If the native host language has an element with an implicit heading and aria-level, such as an HTML heading tag, a native host language element may be used.
  • The button element is the only element inside the heading element. That is, if there are other visually persistent elements, they are not included inside the heading element.
• If the accordion panel associated with an accordion header is visible, the header button element has aria-expanded set to true. If the panel is not visible, aria-expanded is set to false.
• The accordion header button element has aria-controls set to the ID of the element containing the accordion panel content.
• If the accordion panel associated with an accordion header is visible, and if the accordion does not permit the panel to be collapsed, the header button element has aria-disabled set to true.
• Optionally, each element that serves as a container for panel content has role region and aria-labelledby with a value that refers to the button that controls display of the panel.

  • Avoid using the region role in circumstances that create landmark region proliferation, e.g., in an accordion that contains more than approximately 6 panels that can be expanded at the same time.
  • Role region is especially helpful to the perception of structure by screen reader users when panels contain heading elements or a nested accordion.

• The element that contains all elements of the dialog, including the alert message and any dialog buttons, has role alertdialog.
• The element with role alertdialog has either:

  • A value for aria-labelledby that refers to the element containing the title of the dialog if the dialog has a visible label.
  • A value for aria-label if the dialog does not have a visible label.
• The element with role alertdialog has a value set for aria-describedby that refers to the element containing the alert message.

• Breadcrumb trail is contained within a navigation landmark region.
• The landmark region is labelled via aria-label or aria-labelledby.
• The link to the current page has aria-current set to page. If the element representing the current page is not a link, aria-current is optional.

• Toggle button: A two-state button that can be either off (not pressed) or on (pressed). To tell assistive technologies that a button is a toggle button, specify a value for the attribute aria-pressed. For example, a button labelled mute in an audio player could indicate that sound is muted by setting the pressed state true. Important: it is critical the label on a toggle does not change when its state changes. In this example, when the pressed state is true, the label remains "Mute" so a screen reader would say something like "Mute toggle button pressed". Alternatively, if the design were to call for the button label to change from "Mute" to "Unmute," the aria-pressed attribute would not be needed.
• Menu button: as described in the menu button pattern, a button is revealed to assistive technologies as a menu button if it has the property aria-haspopup set to either menu or true.

• Space: Activates the button.
• Enter: Activates the button.
• Following button activation, focus is set depending on the type of action the button performs. For example:

  • If activating the button opens a dialog, the focus moves inside the dialog. (see dialog pattern)
  • If activating the button closes a dialog, focus typically returns to the button that opened the dialog unless the function performed in the dialog context logically leads to a different element. For example, activating a cancel button in a dialog returns focus to the button that opened the dialog. However, if the dialog were confirming the action of deleting the page from which it was opened, the focus would logically move to a new context.
  • If activating the button does not dismiss the current context, then focus typically remains on the button after activation, e.g., an Apply or Recalculate button.
  • If the button action indicates a context change, such as move to next step in a wizard or add another search criteria, then it is often appropriate to move focus to the starting point for that action.
  • If the button is activated with a shortcut key, the focus usually remains in the context from which the shortcut key was activated. For example, if Alt + U were assigned to an "Up" button that moves the currently focused item in a list one position higher in the list, pressing Alt + U when the focus is in the list would not move the focus from the list.

• The button has role of button.
• The button has an accessible label. By default, the accessible name is computed from any text content inside the button element. However, it can also be provided with aria-labelledby or aria-label.
• If a description of the button's function is present, the button element has aria-describedby set to the ID of the element containing the description.
• When the action associated with a button is unavailable, the button has aria-disabled set to true.
• If the button is a toggle button, it has an aria-pressed state. When the button is toggled on, the value of this state is true, and when toggled off, the state is false.

• Buttons for displaying the previous and next slides.
• Optionally, a control, or group of controls, for choosing a specific slide to display. For example, slide picker controls can be marked up as tabs in a tablist with the slide represented by a tabpanel element.
• If the carousel can automatically rotate, it also:

  • Has a button for stopping and restarting rotation. This is particularly important for supporting assistive technologies operating in a mode that does not move either keyboard focus or the mouse.
  • Stops rotating when keyboard focus enters the carousel. It does not restart unless the user explicitly requests it to do so.
  • Stops rotating whenever the mouse is hovering over the carousel.

• If the carousel has an auto-rotate feature, automatic slide rotation stops when any element in the carousel receives keyboard focus. It does not resume unless the user activates the rotation control.
• Tab and Shift + Tab: Move focus through the interactive elements of the carousel as specified by the page tab sequence -- scripting for Tab is not necessary.
• Button elements implement the keyboard interaction defined in the button pattern. Note: Activating the rotation control, next slide, and previous slide do not move focus, so users may easily repetitively activate them as many times as desired.
• If present, the rotation control is the first element in the Tab sequence inside the carousel. It is essential that it precede the rotating content so it can be easily located.
• If tab elements are used for slide picker controls, they implement the keyboard interaction defined in the Tabs Pattern.​

• Basic: Has rotation, previous slide, and next slide controls but no slide picker controls.
• Tabbed: Has basic controls plus a single tab stop for slide picker controls implemented using the tabs pattern.​
• Grouped: Has basic controls plus a series of tab stops in a group of slide picker controls where each control implements the button pattern. Because each slide selector button adds an element to the page tab sequence, this style is the least friendly for keyboard users.

• A carousel container element that encompasses all components of the carousel, including both carousel controls and slides, has either role region or role group. The most appropriate role for the carousel container depends on the information architecture of the page. See the landmark regions guidance to determine whether the carousel warrants being designated as a landmark region.
• The carousel container has the aria-roledescription property set to carousel.
• If the carousel has a visible label, its accessible label is provided by the property aria-labelledby on the carousel container set to the ID of the element containing the visible label. Otherwise, an accessible label is provided by the property aria-label set on the carousel container. Note that since the aria-roledescription is set to "carousel", the label does not contain the word "carousel".
• The rotation control, next slide control, and previous slide control are either native button elements (recommended) or implement the button pattern.
• The rotation control has an accessible label provided by either its inner text or aria-label. The label changes to match the action the button will perform, e.g., "Stop slide rotation" or "Start slide rotation". A label that changes when the button is activated clearly communicates both that slide content can change automatically and when it is doing so. Note that since the label changes, the rotation control does not have any states, e.g., aria-pressed, specified.
• Each slide container has role group with the property aria-roledescription set to slide.
• Each slide has an accessible name:

  • If a slide has a visible label, its accessible label is provided by the property aria-labelledby on the slide container set to the ID of the element containing the visible label.
  • Otherwise, an accessible label is provided by the property aria-label set on the slide container.
  • If unique names that identify the slide content are not available, a number and set size can serve as a meaningful alternative, e.g., "3 of 10". Note: Normally, including set position and size information in an accessible name is not appropriate. An exception is helpful in this implementation because group elements do not support aria-setsize or aria-posinset. The tabbed carousel implementation pattern does not have this limitation.
  • Note that since the aria-roledescription is set to "slide", the label does not contain the word "slide."
• Optionally, an element wrapping the set of slide elements has aria-atomic set to false and aria-live set to:

  • off: if the carousel is automatically rotating.
  • polite: if the carousel is NOT automatically rotating.

• Each slide container has role tabpanel in lieu of group, and it does not have the aria-roledescription property.
• It has slide picker controls implemented using the tabs pattern where:

  • Each control is a tab element, so activating a tab displays the slide associated with that tab.
  • The accessible name of each tab indicates which slide it will display by including the name or number of the slide, e.g., "Slide 3". Slide names are preferable if each slide has a unique name.
  • The set of controls is grouped in a tablist element with an accessible name provided by the value of aria-label that identifies the purpose of the tabs, e.g., "Choose slide to display."
  • The tab, tablist, and tabpanel implement the properties specified in the tabs pattern.

• The set of slide picker controls is contained in an element with role group.
• The group containing the picker controls has an accessible label provided by the value of aria-label that identifies the purpose of the controls, e.g., "Choose slide to display."
• Each picker control is a native button element (recommended) or implements the button pattern.​
• The accessible name of each picker button matches the name of the slide it displays. One technique for accomplishing this is to set aria-labelledby to a value that references the slide group element.
• The picker button representing the currently displayed slide has the property aria-disabled set to true. Note: aria-disabled is preferable to the HTML disabled attribute because this is a circumstance where screen reader users benefit from the disabled button being included in the page Tab sequence.

1. 1.

   Dual-state: The most common type of checkbox, it allows the user to toggle between two choices -- checked and not checked.
2. 2.

   Tri-state: This type of checkbox supports an additional third state known as partially checked.

• If all options in the group are checked, the overall state is represented by the tri-state checkbox displaying as checked.
• If some of the options in the group are checked, the overall state is represented with the tri-state checkbox displaying as partially checked.
• If none of the options in the group are checked, the overall state of the group is represented with the tri-state checkbox displaying as not checked.

• Checking the overall checkbox checks all options in the group.
• Unchecking the overall checkbox will uncheck all options in the group.
• And, In some implementations, the system may remember which options were checked the last time the overall status was partially checked. If this feature is provided, activating the overall checkbox a third time recreates that partially checked state where only some options in the group are checked.

• ​Simple Two-State Checkbox Example: Demonstrates a simple 2-state checkbox.
• ​Tri-State Checkbox Example: Demonstrates how to make a widget that uses the mixed value for aria-checked and group collection of checkboxes with a field set.

• The checkbox has role checkbox.
• The checkbox has an accessible label provided by one of the following:

  • Visible text content contained within the element with role checkbox.
  • A visible label referenced by the value of aria-labelledby set on the element with role checkbox.
  • ​aria-label set on the element with role checkbox.
• When checked, the checkbox element has state aria-checked set to true.
• When not checked, it has state aria-checked set to false.
• When partially checked, it has state aria-checked set to mixed.
• If a set of checkboxes is presented as a logical group with a visible label, the checkboxes are included in an element with role group that has the property aria-labelledby set to the ID of the element containing the label.
• If the presentation includes additional descriptive static text relevant to a checkbox or checkbox group, the checkbox or checkbox group has the property aria-describedby set to the ID of the element containing the description.

• It is displayed only if a certain number of characters are typed in the textbox and those characters match some portion of one of the suggested values.
• It is displayed as soon as the textbox is focused, even if the textbox is empty.
• It is displayed when the Down Arrow key is pressed or the show button is activated, possibly with a dependency on the content of the textbox.
• It is displayed if the value of the textbox is altered in a way that creates one or more partial matches to a suggested value.

1. 1.

   The value for the textbox must be chosen from a predefined set of allowed values, e.g., a location field must contain a valid location name. Note that the listbox and menu button patterns are also useful in this scenario; differences between combobox and alternative patterns are described below.
2. 2.

   The textbox may contain any arbitrary value, but it is advantageous to suggest possible values to the user, e.g., a search field may suggest similar or previous searches to save the user time.

1. 1.

   No autocomplete: When the popup is triggered, the suggested values it contains are the same regardless of the characters typed in the textbox. For example, the popup suggests a set of recently entered values, and the suggestions do not change as the user types.
2. 2.

   List autocomplete with manual selection: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox. The character string the user has typed will become the value of the textbox unless the user selects a value in the popup.
3. 3.

   List autocomplete with automatic selection: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox, and the first suggestion is automatically highlighted as selected. The automatically selected suggestion becomes the value of the textbox when the combobox loses focus unless the user chooses a different suggestion or changes the character string in the textbox.
4. 4.

   List with inline autocomplete: This is the same as list with automatic selection with one additional feature. The portion of the selected suggestion that has not been typed by the user, a completion string, appears inline after the input cursor in the textbox. The inline completion string is visually highlighted and has a selected state.

• ​Examples of ARIA 1.1 Combobox with Listbox Popup: Comboboxes that demonstrate the various forms of autocomplete behavior using a listbox popup and use the ARIA 1.1 implementation pattern.
• ​Example of ARIA 1.1 Combobox with Grid Popup: A combobox that presents suggestions in a grid, enabling users to navigate descriptive information about each suggestion.
• ​ARIA 1.0 Combobox with Both List and Inline Autocomplete: A combobox that demonstrates the autocomplete behavior known as list with inline autocomplete and uses the ARIA 1.0 implementation pattern.
• ​ARIA 1.0 Combobox with List Autocomplete: A combobox that demonstrates the autocomplete behavior known as list with manual selection and uses the ARIA 1.0 implementation pattern.
• ​ARIA 1.0 Combobox Without Autocomplete: A combo box that demonstrates the behavior associated with aria-autocomplete=none and uses the ARIA 1.0 implementation pattern.

• Tab: The textbox is in the page Tab sequence.
• Note: The popup indicator icon or button (if present), the popup, and the popup descendants are excluded from the page Tab sequence.

• Down Arrow: If the popup is available, moves focus into the popup:

  • If the autocomplete behavior automatically selected a suggestion before Down Arrow was pressed, focus is placed on the suggestion following the automatically selected suggestion.
  • Otherwise, places focus on the first focusable element in the popup.
• Up Arrow (Optional): If the popup is available, places focus on the last focusable element in the popup.
• Escape: Dismisses the popup if it is visible. Optionally, clears the textbox.
• Enter: If an autocomplete suggestion is automatically selected, accepts the suggestion either by placing the input cursor at the end of the accepted value in the textbox or by performing a default action on the value. For example, in a messaging application, the default action may be to add the accepted value to a list of message recipients and then clear the textbox so the user can add another recipient.
• Printable Characters: Type characters in the textbox. Note that some implementations may regard certain characters as invalid and prevent their input.
• Standard single line text editing keys appropriate for the device platform (see note below).
• Alt + Down Arrow (Optional): If the popup is available but not displayed, displays the popup without moving focus.
• Alt + Up Arrow (Optional): If the popup is displayed:

  1. 1.

     If the popup contains focus, returns focus to the textbox.
  2. 2.

     Closes the popup.

1. 1.

   include keys for input, cursor movement, selection, and text manipulation.
2. 2.

   Standard key assignments for editing functions depend on the device operating system.
3. 3.

   The most robust approach for providing text editing functions is to rely on browsers, which supply them for HTML inputs with type text and for elements with the contenteditable HTML attribute.
4. 4.

   IMPORTANT: Be sure that JavaScript does not interfere with browser-provided text editing functions by capturing key events for the keys used to perform them.

• Enter: Accepts the focused option in the listbox by closing the popup and placing the accepted value in the textbox with the input cursor at the end of the value.
• Escape: Closes the popup and returns focus to the textbox. Optionally, clears the contents of the textbox.
• Right Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the right. If the input cursor is on the right-most character, the cursor does not move.
• Left Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the left. If the input cursor is on the left-most character, the cursor does not move.
• Any printable character: Returns the focus to the textbox without closing the popup and types the character.
• Backspace (Optional): Returns focus to the textbox and deletes the character prior to the cursor.
• Delete (Optional): Returns focus to the textbox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.
• Down Arrow: Moves focus to and selects the next option. If focus is on the last option, either returns focus to the textbox or does nothing.
• Up Arrow: Moves focus to and selects the previous option. If focus is on the first option, either returns focus to the textbox or does nothing.
• Home (Optional): Either moves focus to and selects the first option or returns focus to the textbox and places the cursor on the first character.
• End (Optional): Either moves focus to the last option or returns focus to the textbox and places the cursor after the last character.

1. 1.

   DOM Focus is maintained on the combobox textbox and the assistive technology focus is moved within the listbox using aria-activedescendant as described in Managing Focus in Composites Using aria-activedescendant.​
2. 2.

   Selection follows focus in the listbox; the listbox allows only one suggested value to be selected at a time for the textbox value.

• Enter: Accepts the currently selected suggested value by closing the popup and placing the selected value in the textbox with the input cursor at the end of the value.
• Escape: Closes the popup and returns focus to the textbox. Optionally, clears the contents of the textbox.
• Any printable character: Returns the focus to the textbox without closing the popup and types the character.
• Backspace (Optional): Returns focus to the textbox and deletes the character prior to the cursor.
• Delete (Optional): Returns focus to the textbox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.
• Right Arrow: Moves focus one cell to the right. Optionally, if focus is on the right-most cell in the row, focus may move to the first cell in the following row. If focus is on the last cell in the grid, either does nothing or returns focus to the textbox.
• Left Arrow: Moves focus one cell to the left. Optionally, if focus is on the left-most cell in the row, focus may move to the last cell in the previous row. If focus is on the first cell in the grid, either does nothing or returns focus to the textbox.
• Down Arrow: Moves focus one cell down. If focus is in the last row of the grid, either does nothing or returns focus to the textbox.
• Up Arrow: Moves focus one cell up. If focus is in the first row of the grid, either does nothing or returns focus to the textbox.
• Page Down (Optional): Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row of the grid, focus does not move.
• Page Up (Optional): Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row of the grid, focus does not move.
• Home (Optional): Either:

  • Moves focus to the first cell in the row that contains focus. Or, if the grid has fewer than three cells per row or multiple suggested values per row, focus may move to the first cell in the grid.
  • Returns focus to the textbox and places the cursor on the first character.
• End (Optional): Either:

  • Moves focus to the last cell in the row that contains focus. Or, if the grid has fewer than three cells per row or multiple suggested values per row, focus may move to the last cell in the grid.
  • Returns focus to the textbox and places the cursor after the last character.
• Control + Home (optional): moves focus to the first row.
• Control + End (Optional): moves focus to the last row.

1. 1.

   DOM Focus is maintained on the combobox textbox and the assistive technology focus is moved within the grid using aria-activedescendant as described in Managing Focus in Composites Using aria-activedescendant.​
2. 2.

   The grid allows only one suggested value to be selected at a time for the textbox value.
3. 3.

   In a grid popup, each suggested value may be represented by either a single cell or an entire row. This aspect of design effects focus and selection movement:

   1. 1.

      If every cell contains a different suggested value:

      • Selection follows focus so that the cell containing focus is selected.
      • Horizontal arrow key navigation typically wraps from one row to another.
      • Vertical arrow key navigation typically wraps from one column to another.
   2. 2.

      If all cells in a row contain information about the same suggested value:

      • Either the row containing focus is selected or a cell containing a suggested value is selected when any cell in the same row contains focus.
      • Horizontal key navigation may wrap from one row to another.
      • Vertical arrow key navigation does not wrap from one column to another.

• Enter: Accepts the currently selected suggested value by closing the popup and placing the selected value in the textbox with the input cursor at the end of the value.
• Escape: Closes the popup and returns focus to the textbox. Optionally, clears the contents of the textbox.
• Any printable character: Returns the focus to the textbox without closing the popup and types the character.
• Right arrow:

  • When focus is on a closed node, opens the node; focus and selection do not move.
  • When focus is on a open node, moves focus to the first child node and selects it if it is selectable.
  • When focus is on an end node, does nothing.
• Left arrow:

  • When focus is on an open node, closes the node.
  • When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node and selects it if it is selectable.
  • When focus is on a root node that is also either an end node or a closed node, does nothing.
• Down Arrow: Moves focus to the next node that is focusable without opening or closing a node and selects it if it is selectable.
• Up Arrow: Moves focus to the previous node that is focusable without opening or closing a node and selects it if it is selectable.
• Home: Moves focus to the first node in the tree without opening or closing a node and selects it if it is selectable.
• End: Moves focus to the last node in the tree that is focusable without opening a node and selects it if it is selectable.

1. 1.

   DOM Focus is maintained on the combobox textbox and the assistive technology focus is moved within the tree using aria-activedescendant as described in Managing Focus in Composites Using aria-activedescendant.​
2. 2.

   The tree allows only one suggested value to be selected at a time for the textbox value.
3. 3.

   In a tree popup, some or all parent nodes may not be selectable values; they may serve as category labels for suggested values. If focus moves to a node that is not a selectable value, either:

   • The previously selected node, if any, remains selected until focus moves to a node that is selectable.
   • There is no selected value.
   • In either case, focus is visually distinct from selection so users can readily see if a value is selected or not.
4. 4.

   If the nodes in a tree are arranged horizontally:

   1. 1.

      Down Arrow performs as Right Arrow is described above, and vice versa.
   2. 2.

      Up Arrow performs as Left Arrow is described above, and vice versa.

• There are two ways to close the popup and return focus to the textbox:

  1. 1.

     Perform an action in the dialog, such as activate a button, that specifies a value for the textbox.
  2. 2.

     Cancel out of the dialog, e.g., press Escape or activate the cancel button in the dialog. Canceling either returns focus to the text box without changing the textbox value or returns focus to the textbox and clears the textbox.
• The dialog implements the keyboard interaction defined in the modal dialog pattern.​

• In a combobox implementing the ARIA 1.1 pattern:

  • The element that serves as the combobox container has role combobox.
  • The element with role combobox contains or owns a textbox element that has either role textbox or role searchbox.
  • When the combobox popup is visible, the combobox element contains or owns an element that has role listbox, tree, grid, or dialog.
  • If the combobox popup has a role other than listbox, the element with role combobox has aria-haspopup set to a value that corresponds to the popup type. That is, aria-haspopup is set to grid, tree, or dialog. Note that elements with role combobox have an implicit aria-haspopup value of listbox.
  • When the combobox popup is visible, the textbox element has aria-controls set to a value that refers to the combobox popup element.
• In a combobox implementing the ARIA 1.0 pattern:

  • The element that serves as the textbox has role combobox.
  • When the combobox popup is visible, the element with role combobox has aria-owns set to a value that refers to an element with role listbox.
  • the element with role combobox has a value for aria-haspopup of listbox. Note that elements with role combobox have an implicit aria-haspopup value of listbox.
• The textbox element has a value for aria-multiline of false. Note that the default value of aria-multiline is false.
• When the combobox popup is not visible, the element with role combobox has aria-expanded set to false. When the popup element is visible, aria-expanded is set to true. Note that elements with role combobox have a default value for aria-expanded of false.
• When a combobox receives focus, DOM focus is placed on the textbox element.
• When a descendant of a listbox, grid, or tree popup is focused, DOM focus remains on the textbox and the textbox has aria-activedescendant set to a value that refers to the focused element within the popup.
• In a combobox with a listbox, grid, or tree popup, when a suggested value is visually indicated as the currently selected value, the option, gridcell, row, or treeitem containing that value has aria-selected set to true.
• If the combobox has a visible label, the element with role combobox has aria-labelledby set to a value that refers to the labelling element. Otherwise, the combobox element has a label provided by aria-label.
• The textbox element has aria-autocomplete set to a value that corresponds to its autocomplete behavior:

  • none: When the popup is displayed, the suggested values it contains are the same regardless of the characters typed in the textbox.
  • list: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox.
  • both: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox. In addition, the portion of the selected suggestion that has not been typed by the user, known as the completion string, appears inline after the input cursor in the textbox. The inline completion string is visually highlighted and has a selected state.

1. 1.

   When referring to the roles, states, and properties documentation for the below list of patterns used for popups, keep in mind that a combobox is a single-select widget where selection always follows focus in the popup.
2. 2.

   The roles, states, and properties for popup elements are defined in their respective design patterns:

   • ​Listbox Roles, States, and Properties​
   • ​Grid Roles, States, and Properties​
   • ​Tree Roles, States, and Properties​
   • ​Dialog Roles, States, and Properties​

• ​Modal Dialog Example: Demonstrates multiple layers of modal dialogs with both small and large amounts of content.
• ​Date Picker Dialog Example: Demonstrates a dialog containing a calendar grid for choosing a date.

• When a dialog opens, focus moves to an element inside the dialog. See notes below regarding initial focus placement.
• Tab:

  • Moves focus to the next tabbable element inside the dialog.
  • If focus is on the last tabbable element inside the dialog, moves focus to the first tabbable element inside the dialog.
• Shift + Tab:

  • Moves focus to the previous tabbable element inside the dialog.
  • If focus is on the first tabbable element inside the dialog, moves focus to the last tabbable element inside the dialog.
• Escape: Closes the dialog.

1. 1.

   When a dialog opens, focus placement depends on the nature and size of the content.

   • In all circumstances, focus moves to an element contained in the dialog.
   • Unless a condition where doing otherwise is advisable, focus is initially set on the first focusable element.
   • If content is large enough that focusing the first interactive element could cause the beginning of content to scroll out of view, it is advisable to add tabindex=-1 to a static element at the top of the dialog, such as the dialog title or first paragraph, and initially focus that element.
   • If a dialog contains the final step in a process that is not easily reversible, such as deleting data or completing a financial transaction, it may be advisable to set focus on the least destructive action, especially if undoing the action is difficult or impossible. The Alert Dialog Pattern is often employed in such circumstances.
   • If a dialog is limited to interactions that either provide additional information or continue processing, it may be advisable to set focus to the element that is likely to be most frequently used, such as an OK or Continue button.
2. 2.

   When a dialog closes, focus returns to the element that invoked the dialog unless either:

   • The invoking element no longer exists. Then, focus is set on another element that provides logical work flow.
   • The work flow design includes the following conditions that can occasionally make focusing a different element a more logical choice:

     1. 1.

        It is very unlikely users need to immediately re-invoke the dialog.
     2. 2.

        The task completed in the dialog is directly related to a subsequent step in the work flow.For example, a grid has an associated toolbar with a button for adding rows. the Add Rows button opens a dialog that prompts for the number of rows. After the dialog closes, focus is placed in the first cell of the first new row.
3. 3.

   It is strongly recommended that the tab sequence of all dialogs include a visible element with role button that closes the dialog, such as a close icon or cancel button.

• The element that serves as the dialog container has a role of dialog.
• All elements required to operate the dialog are descendants of the element that has role dialog.
• The dialog container element has aria-modal set to true.
• The dialog has either:

  • A value set for the aria-labelledby property that refers to a visible dialog title.
  • A label specified by aria-label.
• Optionally, the aria-describedby property is set on the element with the dialog role to indicate which element or elements in the dialog contain content that describes the primary purpose or message of the dialog. Specifying descriptive elements enables screen readers to announce the description along with the dialog title and initially focused element when the dialog opens.

• Because marking a dialog modal by setting aria-modal to true can prevent users of some assistive technologies from perceiving content outside the dialog, users of those technologies will experience severe negative ramifications if a dialog is marked modal but does not behave as a modal for other users. So, mark a dialog modal only when both:

  1. 1.

     Application code prevents all users from interacting in any way with content outside of it.
  2. 2.

     Visual styling obscures the content outside of it.
• The aria-modal property introduced by ARIA 1.1 replaces aria-hidden for informing assistive technologies that content outside a dialog is inert. However, in legacy dialog implementations where aria-hidden is used to make content outside a dialog inert for assistive technology users, it is important that:

  1. 1.

     aria-hidden is set to true on each element containing a portion of the inert layer.
  2. 2.

     The dialog element is not a descendant of any element that has aria-hidden set to true.

• ​Disclosure (Show/Hide) of Image Description​
• ​Disclosure (Show/Hide) of Answers to Frequently Asked Questions​
• ​Disclosure (Show/Hide) for Navigation Menus​

• Enter: activates the disclosure control and toggles the visibility of the disclosure content.
• Space: activates the disclosure control and toggles the visibility of the disclosure content.

• The element that shows and hides the content has role button.
• When the content is visible, the element with role button has aria-expanded set to true. When the content area is hidden, it is set to false.
• Optionally, the element with role button has a value specified for aria-controls that refers to the element that contains all the content that is shown or hidden.

1. 1.

   In the context of a feed, the web page code is responsible for:

   • Appropriate visual scrolling of the content based on which article contains DOM focus.
   • Loading or removing feed articles based on which article contains DOM focus.
2. 2.

   In the context of a feed, assistive technologies with a reading mode are responsible for:

   • Indicating which article contains the reading cursor by ensuring the article element or one of its descendants has DOM focus.
   • providing reading mode keys that move DOM focus to the next and previous articles.
   • Providing reading mode keys for moving the reading cursor and DOM focus past the end and before the start of the feed.

• Page Down: Move focus to next article.
• Page Up: Move focus to previous article.
• Control + End: Move focus to the first focusable element after the feed.
• Control + Home: Move focus to the first focusable element before the feed.

1. 1.

   Due to the lack of convention, providing easily discoverable keyboard interface documentation is especially important.
2. 2.

   In some cases, a feed may contain a nested feed. For example, an article in a social media feed may contain a feed of comments on that article. To navigate the nested feed, users first move focus inside the nested feed. Options for supporting nested feed navigation include:

   • Users move focus into the nested feed from the content of the containing article with Tab. This may be slow if the article contains a significant number of links, buttons, or other widgets.
   • Provide a key for moving focus from the elements in the containing article to the first item in the nested feed, e.g., Alt + Page Down.
   • To continue reading the outer feed, Control + End moves focus to the next article in the outer feed.
3. 3.

   In the rare circumstance that a feed article contains a widget that uses the above suggested keys, the feed navigation key will operate the contained widget, and the user needs to move focus to an element that does not utilize the feed navigation keys in order to navigate the feed.

• The element that contains the set of feed articles has role feed.
• If the feed has a visible label, the feed element has aria-labelledby referring to the element containing the title. Otherwise, the feed element has a label specified with aria-label.
• Each unit of content in a feed is contained in an element with role article. All content inside the feed is contained in an article element.
• Each article element has aria-labelledby referring to elements inside the article that can serve as a distinguishing label.
• It is optional but strongly recommended for each article element to have aria-describedby referring to one or more elements inside the article that serve as the primary content of the article.
• Each article element has aria-posinset set to a value that represents its position in the feed.
• Each article element has aria-setsize set to a value that represents either the total number of articles that have been loaded or the total number in the feed, depending on which value is deemed more helpful to users. If the total number in the feed is undetermined, it can be represented by a aria-setsize value of -1.
• When article elements are being added to or removed from the feed container, and if the operation requires multiple DOM operations, the feed element has aria-busy set to true during the update operation. Note that it is extremely important that aria-busy is set to false when the operation is complete or the changes may not become visible to some assistive technology users.

• A grid is a composite widget so it:

  • Always contains multiple focusable elements.
  • Only one of the focusable elements contained by the grid is included in the page tab sequence.
  • Requires the author to provide code that manages focus movement inside it.
• All focusable elements contained in a table are included in the page tab sequence.

• ​Layout Grid Examples: Three example implementations of grids that are used to lay out widgets, including a collection of navigation links, a message recipients list, and a set of search results.
• ​Data Grid Examples: Three example implementations of grid that include features relevant to presenting tabular information, such as content editing, sort, and column hiding.
• ​Advanced Data Grid Example: Example of a grid with behaviors and features similar to a typical spreadsheet, including cell and row selection.